home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / graphic / pvquan16.zip / PVQUAN.DOC < prev    next >
Text File  |  1992-12-01  |  20KB  |  476 lines
  1.  
  2.                          PVQUANT Version 1.60
  3.  
  4.                      Colour Quantisation Utilities
  5.  
  6.                               for the
  7.  
  8.                     Persistence of Vision Raytracer
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25. Written and Distributed by:  
  26.  
  27. Frank van der Hulst, 101 Epuni St, Lower Hutt, New Zealand 
  28.  
  29. Electronic mail to:  
  30. UseNet:  f_vander@comp.vuw.ac.nz, 
  31.          frank@cit.ac.nz,
  32.          frank@whare.cavebbs.welly.gen.nz 
  33. FidoNet: frank vanderhulst at GenBoard (Node 3:771/160)
  34.  
  35. 01 December 1992
  36. ─────────────────────────────────────────────────────────────────────────── 
  37.  
  38. These programs are freely distributable.  The authors retain the copyright 
  39. to the program but authorizes free distribution by BBS'es, networks, 
  40. magnetic media, etc.  The distributor may charge no more than five dollars 
  41. ($5) U.S.  for this software.  
  42.  
  43. The images and data files generated by these programs are the property of 
  44. the user of the software and may be used for any purpose without 
  45. restriction.  
  46.  
  47. The authors make no guarantees or warranties with these programs and claim 
  48. no responsibility for any damage or loss of time caused by this program.  
  49. Bug reports may be sent to the authors but the authors are under no 
  50. obligation to provide bug fixes, features, or any support for this software.  
  51.  
  52. The following conditions are placed on the use of this program:  
  53.  
  54. 1) That it should not be used as part of any commercial package without the 
  55. explicit written consent of the author.  
  56.  
  57. 2) If you make any changes to the source code, please let me know.  That's 
  58. the way this program was built!  
  59.  
  60. 3) This text file must accompany the program.  
  61.  
  62. This manual is divided into the following sections:  
  63.  
  64. 1) Archive Description 
  65. 2) Getting Started
  66. 3) Command Line Parameters
  67. 4) Output File Format
  68. 5) Source Code Information
  69. 6) Displaying the Images
  70. 7) Animation
  71. 8) Porting to Different Platforms
  72. 2) Background
  73.  
  74. 1) Archive Description 
  75. ~~~~~~~~~~~~~~~~~~~~~~ 
  76. This archive contains C source code for a set of programs to convert image
  77. files produced by DKB-Trace or Persistence of Vision raytracer into a format
  78. suitable for display on a VGA screen, or to GIF format.  It includes
  79. programs to generate a single stereoscopic 3D image from two views of a
  80. scene, as well as programs to produce animation from multiple ray-traced
  81. images.  
  82.  
  83. The programs (or large parts of them) were written by several different 
  84. people.  All of the programs are in the public domain to some extent, with 
  85. some restrictions put on them by their respective authors.  I have collected 
  86. these from various places, ported them to Turbo-C, GNU C, or IBM C Set/2 if 
  87. necessary, and formatted them in a way that I like.  The copyright for each 
  88. program still belongs to its author -- my copyright claim extends only to 
  89. the collection of programs (like the editor of a journal, for example).  
  90.  
  91. QUANT (HECKBERT & OCTREE):  Colour quantisation program which post-processes 
  92. raw or Targa image files produced by the Persistence of Vision Ray Tracer
  93. (PoVRay). Two versions can be compiled:  one uses Heckbert's
  94. median-splitting algorithm, whereas the other uses Octree quantisation.
  95.  
  96. DISPLAY:  Displays either 320x400 or 320x200 images, either 2D, or stereo 
  97. 3D.  3D images require Sega 3D-glasses to be connected to the serial port 
  98. for viewing.  
  99.  
  100. ANIMDAT:  Reads an animation source file (*.VAR), and uses it to generate
  101. data files for the PoV ray tracer.  
  102.  
  103. ANIMGIF:  Produces a .GIF file containing a series of images to be displayed 
  104. by ANIM.  
  105.  
  106. ANIMFLI:  Produces a .FLI file containing a series of images to be displayed 
  107. by a .FLI player (e.g.  Autodesk's AAPLAY).  
  108.  
  109.  
  110.  
  111. 2) Getting Started
  112. ~~~~~~~~~~~~~~~~~~ 
  113. Before quantising an image, you must create one!  Use either DKB-TRACE or
  114. PoVRAY to produce output in the "Targa" format.
  115.  
  116. I use the following command line:  
  117.  
  118. POVRAY -ipacman.dat -opacman.tga -w320 -h400 -v +ft +p +x -a
  119.  
  120. See the raytracer documentation on what all the above mean.  Most important 
  121. is the "+ft" option which tells the raytracer to produce "Targa" files.  The 
  122. quantiser can also read "raw" format files (use the "+fr" switch).  If you 
  123. use this (there's no real reason why you should) and run POVRAY on a PC,
  124. you'll probably need to rename the files produced.  By default it gives 
  125. extensions of .R8, .G8, and .B8, whereas QUANT needs extensions of .RED, 
  126. .GRN, and .BLU.  
  127.  
  128. Now try running the OCTREE quantiser program:  
  129.  
  130. OCTREE pacman 
  131.  
  132. 3) Command Line Parameters
  133. ~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  134. QUANT is a program to convert image files produced by DKB-Trace or
  135. Persistence of Vision raytracer into a format suitable for display on a VGA
  136. screen.  
  137.  
  138. To do this, it must select 256 colours from a palette of 256K colours to 
  139. best represent the colours in the image file which are selected from a 
  140. palette of 16 million.  In other words, it must "quantise" the colours in 
  141. the image file (which are selected from a palette of 16 million) into a set 
  142. of 256 colours selected from a palette of 256K colours.  
  143.  
  144. QUANT is a colour quantisation program which post-processes raw or 
  145. Targa image files produced by the Persistence of Vision Ray Tracer (PoV 
  146. Ray). Two versions can be compiled:  one uses Heckbert's median-splitting
  147. algorithm, whereas the other uses Octree quantisation.  The Heckbert version
  148. takes much longer to run, especially on a 286.  On the other hand, it
  149. produces much better results.  The Octree version is faster, but not as
  150. good.  
  151.  
  152. As an additional feature, the program allows the user to generate a single 
  153. palette from several image files, thus making it possible to produce a 
  154. stereoscopic 3D image from two views of a scene, or animation.  
  155.  
  156. Command line format:  
  157.  
  158. HECKBERT [-C=colours][-W=width][-H=height][-D=display][-T=type] 
  159.          [-O=outputbits][-S=speed][-N=numfiles] file_name
  160.  
  161. or 
  162.  
  163. OCTREE [-C=colours][-W=width][-H=height][-D=display][-T=type] 
  164.        [-O=outputbits][-N=numfiles] file_name
  165.  
  166. If no parameters are given, a usage message is shown.  
  167.  
  168.                                                             Default value
  169. outputbits = bits per colour being output                   [6]
  170. intype = 0 or 1 to select input format                      [0]
  171.             0 selects raw files (.RED, .GRN,.BLU)
  172.             1 selects Targa (.TGA)
  173. type = 0, 1 or 2 to select output format                    [1]
  174.             0 selects 4-planar  output for 320x400 or 320x200 images
  175.             1 selects linear output
  176.             2 selects GIF output.
  177. display = 1 to display while outputting                     [1]
  178.             Only available on the PC.
  179. colours = number of separate colours to produce             [256]
  180. width = number of pixels wide the image is                  [320]
  181. height = number of pixels high the image is                 [200]
  182. speed = 1 or 0 for fast or slow quantisation                [0]
  183.             Heckbert speed switch.  If zero, the program does another pass
  184.             through the data, to find the optimal palette selection.  This
  185.             pass is much slower than the earlier passes, and produces
  186.             slightly better results.
  187. numfiles = number of files to convert                       [1]
  188.             If  numfiles = 1, QUANT calculates a palette for that file and
  189.             writes it to disk with a .2D extension.  
  190.             If numfiles = 2, QUANT calculates one combined palette from both
  191.             images, then writes this palette, as well as the data from
  192.             both files to an output file with a .3D extension.  
  193.             If numfiles > 2, QUANT assumes this is an animation sequence, 
  194.             and generates one palette for all the files, then writes the
  195.             output in the form of several 2D-format files (one for each 
  196.             input file), all with the same palette.  The files are named
  197.             FILE_0.0, FILE_0.1, FILE_0.2, ...
  198.  
  199. file_name   the base part of the filename(s) of files to be converted -- a
  200.             numeric part and an extension are added automatically.  The
  201.             nu